<html>

<head>
<title>HTML Generation Facility</title>
<meta name="GENERATOR" content="Microsoft FrontPage 3.0">
</head>

<body>

<h1 align="center"><strong>HTML Generation Facility</strong></h1>

<p><small><small>This document copyright (c) 2000 Franz Inc.</small></small></p>

<h2>Introduction</h2>

<p>We've defined a pair of macros which enable&nbsp; a program to generate <strong>html</strong>
in a concise and readable&nbsp; manner.&nbsp;&nbsp; These macros are quite a bit different
than those found in other <strong>html </strong>generation systems and thus we'll briefly
describe the justification for this design.</p>

<p><strong>html</strong> is a concise markup language. There is a tendency in language
design to assume that one's users won't be as smart as one's self and thus one tends to
dumb things down.&nbsp; For example, <strong>html</strong> uses <strong>&lt;p&gt;</strong>
to start a&nbsp; paragraph.&nbsp; The language designer says to himself: &quot;while I
know that <strong>p</strong> means paragraph, my users won't so I'll spell it out as <strong>with-paragraph</strong>.&quot;
&nbsp;&nbsp; A similar thing is done for all the other html commands and soon a program to
generate html contains so many long markup commands that it's hard to see the text of the
document from the markup commands.&nbsp; A second problem is that as a user you're not
sure exactly what <strong>html</strong> will be generated by some high level <strong>with</strong>-<strong>xxx
</strong>forms.&nbsp;&nbsp; If you're trying to generate a particular sequence of <strong>html</strong>
you're left experimenting with the high level forms and hoping that by luck you get the
output you want.&nbsp;&nbsp;&nbsp; A third problem is that with the high level forms
you're forced to learn yet another markup language.&nbsp; There are plenty of books and
reference guides to <strong>html</strong> itself and it's an easy language to master.
&nbsp;&nbsp; Learning&nbsp; a particular high-level mapping of <strong>html </strong>is an
added burden.</p>

<p>With our <strong>html</strong> generation macros you write the actual <strong>html </strong>and
we just eliminate some of the tedious parts, such as closing off markup commands. &nbsp;
The result is that the structure of the document is visible and you can use any book on <strong>html</strong>
as a reference.</p>

<h2>Example</h2>

<p>The following example of generated web page will be useful to refer to in the
discussion below of the syntax of the <strong>html</strong> macro.</p>

<pre>(html (:html
          (:head (:title &quot;My Document&quot;))
          (:body (:h1 &quot;My Document&quot;)
            &quot;Hello AllegroServe, the time is &quot;
            (:prin1 (get-universal-time))

            (incf *my-counter*) ; evaluated but not printed
)))</pre>

<p>&nbsp;</p>

<p>This particular example generates a complete web page, but it's possible to use the
&nbsp; <strong>html</strong> macro to generate partial pages as well.&nbsp;&nbsp; In this
example, the generated page is surrounded by <strong>&lt;html&gt;</strong> and <strong>&lt;/html&gt;</strong>
due to the <strong>:html</strong> form.&nbsp;&nbsp;&nbsp; The page contains a header and a
body surrounded by their respective html markers.&nbsp; The body of the document contains
a level 1 header followed by the text beginning &quot;Hello, AllegroServe&quot;.
&nbsp;&nbsp; Following that is printed the universal time at the time that the page is
generated (i.e now rather than when the macro was first processed by lisp). &nbsp;&nbsp;
The following <strong>incf</strong> expression is evaluated but the result is not
printed.&nbsp;&nbsp; In this case we're keeping a private count of the number of times
this page has been accessed.</p>

<h2>html macro</h2>

<p>Now that you have a sense of how the <strong>html</strong> macro works, we will
describe the syntax in detail.</p>

<p>&nbsp;</p>

<p><strong><font face="Courier New">(html <em>form1 form2 ... formn) </font>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
</em>[Macro]</strong></p>

<p>The forms are processed from left to right.&nbsp; The most&nbsp; likely effect is that
html output is generated.&nbsp; The output is sent to the stream htmlgen:*html-stream*.
&nbsp; The action taken depends on what the form looks like at macro-expansion time.
&nbsp;&nbsp; The possibilities are: 

<ul>
  <li>string -&nbsp; A string is simply written (using <strong>princ</strong>) to the output
    stream.&nbsp;&nbsp; Thus the string could contain embedded html commands.</li>
  <li>keyword symbol -&nbsp; The keyword must name a known html operator.&nbsp;&nbsp; The
    result is that the associated html markup command is sent to the output stream.&nbsp; The
    mapping of keyword to html command is trivial -- the print name of the keyword is the html
    command.&nbsp; So <strong>:p</strong>&nbsp; emits <strong>&lt;p&gt;</strong>.</li>
  <li>list beginning with a keyword symbol - This names an <strong>html</strong> operator that
    may or may not have an associated inverse operator beginning with &quot;/&quot;.&nbsp; The
    typical result of this form is to emit the associated html markup command, then process
    the items in the list in the same way as the forms are processed, and then emit the
    inverse markup command.&nbsp; Thus <strong>(:i &quot;foo&quot;)</strong> emits <strong>&lt;i&gt;foo&lt;/i&gt;.
    &nbsp; </strong>&nbsp;&nbsp; There is a special case when a single element list is given
    (see below for details).&nbsp; Also there are some special keywords that are commands to
    the <strong>html</strong> macro rather than markup commands.&nbsp; They are described
    below.</li>
  <li>list beginning with a list beginning with a keyword symbol - This is used to specify
    markup commands that have arguments.&nbsp; For example <br>
    <strong>((:a href &quot;/foo/bar.html&quot;) &quot;the link&quot;)</strong> turns into <strong>&lt;a
    href=&quot;/foo/bar.html&quot;&gt;the link&lt;/a&gt;</strong>.&nbsp;&nbsp;&nbsp; The
    arguments are in plist form.&nbsp; The keyword names are not evaluated, they should be
    symbols or strings.&nbsp; The values are evaluated and printed with <strong>prin1</strong>.</li>
  <li>anything else&nbsp; - everything else is simply evaluated in the normal lisp way and the
    value thrown away.</li>
</ul>

<p>Special cases: 

<ul>
  <li><strong>(:princ </strong>arg1 arg2 .. argn<strong>) </strong>causes the result of
    evaluating each of the args to be printed to the html stream using the <strong>princ</strong>
    function (which prints without inserting escape characters needed by the lisp reader to
    read the result).</li>
  <li><strong>(:prin1</strong> arg1 arg2 ... argn<strong>) </strong>causes the result of
    evaluating each of the args to be printed to the html stream using the <strong>prin1 </strong>function
    (which prints by inserting escape characters needed by the lisp reader to read the
    result).</li>
  <li><strong>(:princ-safe </strong>arg1 arg2 .. argn<strong>) </strong>acts like the <strong>:princ</strong>
    case except that the output is scanned for characters that could be considered html markup
    commands, and if found, these characters are escaped to prevent them from being treated as
    html markup commands.</li>
  <li><strong>(:prin1-safe </strong>arg1 arg2 .. argn<strong>) </strong>acts like the <strong>:prin1</strong>
    case except that the output is scanned for characters that could be considered html markup
    commands, and if found, these characters are escaped to prevent them from being treated as
    html markup commands.</li>
  <li><strong>:newline </strong>simply inserts a newline into the html output stream.
    &nbsp;&nbsp; This will not have an effect on the result as viewed by a web browser (unless
    it is emitted while inside an html markup command that specifies preformatted input).
    &nbsp; The main use for this is to make the resulting html file easier to read by a human.</li>
  <li>You can conditionally specify arguments to a markup command using an argument name of
    &nbsp; <strong>:if*</strong>. Following the <strong>:if*</strong> is a lisp expression
    which if true at runtime will cause the following argument value pair to be included in
    the argument tag.&nbsp; For example <strong>((:td :if* (frob) :bgcolor
    &quot;#00ff00&quot;) &quot;xx&quot;) </strong>will only put <strong>bgcolor=&quot;#00ff00&quot;</strong>
    in the argument if the expression <strong>(frob)</strong> returns true at runtime.</li>
</ul>

<p>&nbsp;</p>

<p>&nbsp;</p>

<p><strong><font face="Courier New">(html-stream <em>stream</em>&nbsp; <em>form1 form2 ...
formn)</font>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
</em>[Macro]</strong></p>

<p>This binds htmlgen:*html-stream* to the value of the stream argument and then evaluates
the <em>form<strong> </strong></em>arguments just like the <strong>html</strong> macro. </p>

<p>&nbsp;</p>

<h2>Examples</h2>

<p>We will show how to build a page containing a table using successively more runtime
customization of the table.&nbsp; First we show how to build a table of squares.</p>

<pre>(defun simple-table-a ()
   (with-open-file (p &quot;~/public_html/test.html&quot;
        :direction :output
        :if-exists :supersede)

     (html-stream p 
        (:html
         (:head (:title &quot;Test Table&quot;))
         (:body 
           (:table 
            (:tr (:td &quot;0&quot;) (:td &quot;0&quot;))
            (:tr (:td &quot;1&quot;) (:td &quot;1&quot;))
            (:tr (:td &quot;2&quot;) (:td &quot;4&quot;))
            (:tr (:td &quot;3&quot;) (:td &quot;9&quot;))
            (:tr (:td &quot;4&quot;) (:td &quot;16&quot;))
            (:tr (:td &quot;5&quot;) (:td &quot;25&quot;))))))))</pre>

<p>The function <strong>simple-table-a </strong>builds a page containing this table:</p>

<table>
  <tr>
    <td>0</td>
    <td>0</td>
  </tr>
  <tr>
    <td>1</td>
    <td>1</td>
  </tr>
  <tr>
    <td>2</td>
    <td>4</td>
  </tr>
  <tr>
    <td>3</td>
    <td>9</td>
  </tr>
  <tr>
    <td>4</td>
    <td>16</td>
  </tr>
  <tr>
    <td>5</td>
    <td>25</td>
  </tr>
</table>

<p>It isn't very pretty but it's easy to see the correspondence between the <strong>html</strong>
macro and the resulting table.&nbsp; Note that if we had done, for example, <strong>(:td
1)</strong> instead of <strong>(:td &quot;1&quot;)</strong> then nothing would have been
emitted.&nbsp;&nbsp; Only constant strings are printed, not constant integers.&nbsp; To
use an integer here we would have had to do <strong>(:td (:princ 1))</strong>.</p>

<p>We can use the ability to pass arguments to html markup commands to specify a border
around the elements of the table as shown here:</p>

<pre>(defun simple-table-b ()
  (with-open-file (p &quot;~/public_html/test.html&quot;
        :direction :output
        :if-exists :supersede)

    (html-stream p 
        (:html
         (:head (:title &quot;Test Table&quot;))
         (:body <strong>
          </strong>(<strong>(:table border 2)</strong>
            (:tr (:td &quot;0&quot;) (:td &quot;0&quot;))
            (:tr (:td &quot;1&quot;) (:td &quot;1&quot;))
            (:tr (:td &quot;2&quot;) (:td &quot;4&quot;))
            (:tr (:td &quot;3&quot;) (:td &quot;9&quot;))
            (:tr (:td &quot;4&quot;) (:td &quot;16&quot;))
            (:tr (:td &quot;5&quot;) (:td &quot;25&quot;))))))))
</pre>

<p>The resulting table is:</p>

<table border="2">
  <tr>
    <td>0</td>
    <td>0</td>
  </tr>
  <tr>
    <td>1</td>
    <td>1</td>
  </tr>
  <tr>
    <td>2</td>
    <td>4</td>
  </tr>
  <tr>
    <td>3</td>
    <td>9</td>
  </tr>
  <tr>
    <td>4</td>
    <td>16</td>
  </tr>
  <tr>
    <td>5</td>
    <td>25</td>
  </tr>
</table>

<p><br>
Suppose we wanted to make the table include the squares of numbers from zero to 100.
&nbsp; That would take a lot of typing.&nbsp; Instead, let's modify the table generation
function to compute a table of any size:</p>

<pre>(defun simple-table-c (count)
  (with-open-file (p &quot;~/public_html/test.html&quot;
        :direction :output
        :if-exists :supersede)

    (html-stream p 
        (:html
          (:head (:title &quot;Test Table&quot;))
          (:body 
           ((:table border 2)
            <strong>(dotimes (i count)
              (html (:tr (:td (:princ i))
                         (:td (:princ (* i i))))))</strong>))))))</pre>

<p>&nbsp;</p>

<p>Note that we can freely imbed calls to the <strong>html</strong> macro within another
call.&nbsp;&nbsp; The <strong>dotimes</strong> call inside the <strong>:body</strong>
expression is simply evaluated and its value ignored.&nbsp; However the side effect of the
<strong>dotimes</strong> is to generate more html and to send it to the stream bound in
the <strong>html-stream</strong> call.&nbsp; The result of <font face="Courier New">(simple-table-c
8)</font> is</p>

<table border="2">
  <tr>
    <td>0</td>
    <td>0</td>
  </tr>
  <tr>
    <td>1</td>
    <td>1</td>
  </tr>
  <tr>
    <td>2</td>
    <td>4</td>
  </tr>
  <tr>
    <td>3</td>
    <td>9</td>
  </tr>
  <tr>
    <td>4</td>
    <td>16</td>
  </tr>
  <tr>
    <td>5</td>
    <td>25</td>
  </tr>
  <tr>
    <td>6</td>
    <td>36</td>
  </tr>
  <tr>
    <td>7</td>
    <td>49</td>
  </tr>
</table>

<p>&nbsp;</p>

<p>We can specify at runtime values for the arguments to html markup forms.&nbsp; This
function allows us to specify parameters of the table being built:</p>

<pre>(defun simple-table-d (count border-width backg-color border-color)
  (with-open-file (p &quot;~/public_html/test.html&quot;
        :direction :output
        :if-exists :supersede)

     (html-stream p 
        (:html
         (:head (:title &quot;Test Table&quot;))
         (:body 
           (<strong>(:table border border-width
                bordercolor border-color
                bgcolor backg-color
                cellpadding 3)</strong>
            (:tr ((:td bgcolor &quot;blue&quot;) 
                  ((:font :color &quot;white&quot; :size &quot;+1&quot;)
                   &quot;Value&quot;))
                 ((:td bgcolor &quot;blue&quot;) 
                  ((:font :color &quot;white&quot; :size &quot;+1&quot;)
                   &quot;Square&quot;))
            )
            (dotimes (i count)
             (html (:tr (:td (:princ i))
                        (:td (:princ (* i i))))))))))))
        </pre>

<p>This demonstrates that in an html markup command argument list the keywords aren't
evaluated but the values are.&nbsp;&nbsp; If we evaluate this expression:</p>

<pre>(simple-table-d 10 3 &quot;silver&quot; &quot;blue&quot;)</pre>

<p>then we generate this table:</p>

<table border="3" bordercolor="blue" bgcolor="silver" cellpadding="3">
  <tr>
    <td bgcolor="blue"><font color="white" size="+1">Value</font></td>
    <td bgcolor="blue"><font color="white" size="+1">Square</font></td>
  </tr>
  <tr>
    <td>0</td>
    <td>0</td>
  </tr>
  <tr>
    <td>1</td>
    <td>1</td>
  </tr>
  <tr>
    <td>2</td>
    <td>4</td>
  </tr>
  <tr>
    <td>3</td>
    <td>9</td>
  </tr>
  <tr>
    <td>4</td>
    <td>16</td>
  </tr>
  <tr>
    <td>5</td>
    <td>25</td>
  </tr>
  <tr>
    <td>6</td>
    <td>36</td>
  </tr>
  <tr>
    <td>7</td>
    <td>49</td>
  </tr>
  <tr>
    <td>8</td>
    <td>64</td>
  </tr>
  <tr>
    <td>9</td>
    <td>81</td>
  </tr>
</table>

<p>&nbsp;</p>

<p>&nbsp;</p>

<p>An example of conditional arguments to a markup command is this:</p>

<pre>(defun simple-table-e (count)
   (with-open-file (p &quot;~/public_html/test.html&quot;
        :direction :output
        :if-exists :supersede)

     (html-stream p 
        (:html
          (:head (:title &quot;Test Table&quot;))
          (:body 
            ((:table border 2)
             (dotimes (i count)
              (html (:tr 
               (dotimes (j count)
                 (html ((:td <strong>:if* (evenp j) :bgcolor &quot;red&quot;
                             :if* (not (evenp j)):bgcolor &quot;green&quot;</strong>)
                        (:princ (* i j))))))))))))))
</pre>

<p>This sets the color of the columns to alternately red and green:&nbsp; Here is <font
face="Courier New">(simple-table-e 6)</font></p>

<table border="2">
  <tr>
    <td bgcolor="red">0</td>
    <td bgcolor="green">0</td>
    <td bgcolor="red">0</td>
    <td bgcolor="green">0</td>
    <td bgcolor="red">0</td>
    <td bgcolor="green">0</td>
  </tr>
  <tr>
    <td bgcolor="red">0</td>
    <td bgcolor="green">1</td>
    <td bgcolor="red">2</td>
    <td bgcolor="green">3</td>
    <td bgcolor="red">4</td>
    <td bgcolor="green">5</td>
  </tr>
  <tr>
    <td bgcolor="red">0</td>
    <td bgcolor="green">2</td>
    <td bgcolor="red">4</td>
    <td bgcolor="green">6</td>
    <td bgcolor="red">8</td>
    <td bgcolor="green">10</td>
  </tr>
  <tr>
    <td bgcolor="red">0</td>
    <td bgcolor="green">3</td>
    <td bgcolor="red">6</td>
    <td bgcolor="green">9</td>
    <td bgcolor="red">12</td>
    <td bgcolor="green">15</td>
  </tr>
  <tr>
    <td bgcolor="red">0</td>
    <td bgcolor="green">4</td>
    <td bgcolor="red">8</td>
    <td bgcolor="green">12</td>
    <td bgcolor="red">16</td>
    <td bgcolor="green">20</td>
  </tr>
  <tr>
    <td bgcolor="red">0</td>
    <td bgcolor="green">5</td>
    <td bgcolor="red">10</td>
    <td bgcolor="green">15</td>
    <td bgcolor="red">20</td>
    <td bgcolor="green">25</td>
  </tr>
</table>

<p>&nbsp;</p>

<p>&nbsp;</p>

<p>&nbsp;</p>

<h2>HTML generation functions</h2>

<p>It's possible to express HTML using Lisp data structures.&nbsp;&nbsp; The form is based
on how HTML is written using the <strong>html</strong> macro above.&nbsp; </p>

<p>Lisp HTML (<strong>lhtml) </strong> is defined as one of the following

<ul>
  <li>a string, which is rendered as HTML by simply printing it.&nbsp; Thus the string can
    contain embedded HTML commands.</li>
  <li>a list beginning with a valid <strong>lhtml</strong> keyword and containing <strong>lhtml</strong>
    forms.&nbsp;&nbsp; The valid keywords are those corresponding to the HTML entity tags,
    plus the special tags <strong>:princ, :princ-safe, :prin1, :prin1-safe</strong>, <strong>:newline</strong>
    and <strong>:comment</strong>.&nbsp;&nbsp; These act just as they do in the <strong>html</strong>
    macro.&nbsp;&nbsp; This form is rendered as an opening tag, then the rendering of the
    body, and a closing HTML tag if one exists.</li>
  <li>a list beginning with a list beginning with an <strong>lhtml</strong> keyword.
    &nbsp; This is the form used when arguments are to be supplied with the opening entity
    tag.&nbsp; </li>
</ul>

<p>Examples of valid <strong>lhtml</strong>:

<ul>
  <li>&quot;foo&lt;i&gt;bar&lt;/i&gt;baz&quot;</li>
  <li>(:i &quot;foo&quot;)</li>
  <li>((:body :bgcolor &quot;#xffffff&quot;) &quot;the body&quot;)</li>
</ul>

<p>&nbsp;</p>

<p><strong><font face="Courier New">(html-print lhtml stream)</font></strong></p>

<p>Print the Lisp HTML expression <strong>lhtml</strong> to the <strong>stream.</strong></p>

<p><strong>&nbsp;</strong></p>

<p><font face="Courier New"><strong>(html-print-list lhtml-list stream)</strong></font></p>

<p>Print the list of <strong>lhtml</strong> forms to the <strong>stream.&nbsp;&nbsp; </strong>
This is equivalent to calling <strong>html-print</strong> on every element of <strong>lhtml-list</strong>.
</p>

<p>&nbsp;</p>

<p>&nbsp;</p>

<p>&nbsp;</p>
</body>
</html>
